Asp |
您所在的位置：网站首页 › gg group › Asp |
Asp
|
前言
对于Web API应用程序而言，随着时间的推移以及需求的增加或改变，API必然会遇到升级的需求。事实上，Web API应用程序应该从创建时就考虑到API版本的问题。业务的调整、功能的增加、接口的移除与改名、接口参数变动、实体属性的添加、删除和更改等都会改变API的功能，从而带来版本的变更。 现有的资料大部分是使用 Microsoft.AspNetCore.Mvc.Versioning 这个包，但我实际使用的时候发现这个包早就不更新了，微软官方文档好像也没有这部分介绍，不过在这个包的nuget主页上有说已经换成新的 Asp.Versioning.Mvc 包，原来是微软改名部发力了，失敬失敬~ 😂 好在这个新的包在Github上有很详细的文档，但这改名速度实在是猛，为了实现这个功能，我走了不少弯路。😂 OK，本文基于 .Net6.0，以 AspNetCore WebApi 为例，介绍引入API版本管理的过程。 基础指定版本的方法有两种，既可以使用[ApiVersion]特性，也可以使用版本约定方式。当定义了不同版本的API接口后，客户端可以通过如下多种方式来访问某一版本的API。 使用URL路径，如 api/v1.0/values 使用查询字符串，如 api/values?api-version=1.0 使用HTTP自定义消息头 使用媒体类型（Media Type）参数，如 Accept: application/json;v=2.0ASP.NET Core MVC默认的方式是使用查询字符串，查询字符串使用的参数名为api-version。具体使用哪种方式由服务端指定（用下面介绍的 ApiVersionReader 属性来配置），既可以使用其中的一种，也可以同时使用多种不同的方式。 API版本的格式由主版本号与次版本号组成，此外还可以包含可选的两部分：版本组和状态。 [Version Group.].[-Status] [[.Minor]][-Status]版本组的格式为YYYY-MM-DD，它能够对API接口起到逻辑分组的作用，状态则能够标识当前版本的状况，如Alpha、Beta和RC等。以下是常见的版本格式： /api/foo?api-version=1.0 /api/foo?api-version=2.0-Alpha /api/foo?api-version=2015-05-01.3.0 /api/v1/foo /api/v2.0-Alpha/foo /api/v2015-05-01.3.0/foo本文采用 /api/v1/foo 形式 安装依赖需要安装这俩nuget包 Asp.Versioning.Mvc Asp.Versioning.Mvc.ApiExplorer 注册服务编辑 Program.cs 文件 builder.Services.AddApiVersioning(options => { options.DefaultApiVersion = new ApiVersion(1, 0); options.AssumeDefaultVersionWhenUnspecified = true; options.ReportApiVersions = true; options.ApiVersionReader = ApiVersionReader.Combine( new UrlSegmentApiVersionReader(), new HeaderApiVersionReader("x-api-version"), new MediaTypeApiVersionReader("ver") ); }) .AddMvc() .AddApiExplorer(options => { options.GroupNameFormat = "'v'VVV"; options.SubstituteApiVersionInUrl = true; });以上代码做了这些事： DefaultApiVersion 设置默认版本为1.0 AssumeDefaultVersionWhenUnspecified 没有指定版本时，使用默认版本 ReportApiVersions 在响应头里加上可用的接口版本 ApiVersionReader 定义了可以从三个地方获取接口版本信息，URL里和俩请求头 GroupNameFormat 指定了版本名称格式，详见下表 SubstituteApiVersionInUrl 因为要使用URL指定版本，所以这里设置为true API Version Format Strings本文中我使用的是 'v'VVV 的格式 Format Specifier Description Examples F Full API version as [group version][.major[.minor]][-status] 2017-05-01.1-RC -> 2017-05-01.1-RC FF Full API version with optional minor version as [group version][.major[.minor,0]][-status] 2017-05-01.1-RC -> 2017-05-01.1.0-RC G Group version as yyyy-MM-dd 2017-05-01.1-RC -> 2017-05-01 GG Group version as yyyy-MM-dd with status 2017-05-01.1-RC -> 2017-05-01-RC y Group version year from 0 to 99 2001-05-01.1-RC -> 1 yy Group version year from 00 to 99 2001-05-01.1-RC -> 01 yyy Group version year with a minimum of three digits 2017-05-01.1-RC -> 017 yyyy Group version year as a four-digit number 2017-05-01.1-RC -> 2017 M Group version month from 1 through 12 2001-05-01.1-RC -> 5 MM Group version month from 01 through 12 2001-05-01.1-RC -> 05 MMM Group version abbreviated name of the month 2001-06-01.1-RC -> Jun MMMM Group version full name of the month 2001-06-01.1-RC -> June d Group version day of the month, from 1 through 31 2001-05-01.1-RC -> 1 dd Group version day of the month, from 01 through 31 2001-05-01.1-RC -> 01 ddd Group version abbreviated name of the day of the week 2001-05-01.1-RC -> Mon dddd Group version full name of the day of the week 2001-05-01.1-RC -> Monday v Minor version 2001-05-01.1-RC -> 1 1.1 -> 1 V Major version 1.0-RC -> 1 2.0 -> 2 VV Major and minor version 1-RC -> 1 1.1-RC -> 1.1 1.1 -> 1.1 VVV Major, optional minor version, and status 1-RC -> 1-RC 1.1 -> 1.1 VVVV Major, minor version, and status 1-RC -> 1.0-RC 1.1 -> 1.1 1 -> 1.0 S Status 1.0-Beta -> Beta p Padded minor version with default of two digits 1.1 -> 01 1 -> 00 p[n] Padded minor version with N digits p2: 1.1 -> 01 p3: 1.1 -> 001 P Padded major version with default of two digits 2.1 -> 02 2 -> 02 P[n] Padded major version with N digits P2: 2.1 -> 02 P3: 2.1 -> 002 PP Padded major and minor version with a default of two digits 2.1 -> 02.01 2 -> 02.00 PPP Padded major, optional minor version, and status with a default of two digits 1-RC -> 01-RC 1.1-RC -> 01.01-RC PPPP Padded major, minor version, and status with a default of two digits 1-RC -> 01.00-RC 1.1-RC -> 01.01-RC 设置API版本例子接口有俩版本 /api/v1/demo/test /api/v2/demo/test在 Controller 下创建俩目录，v1 和 v2，然后分别创建Controller 上代码 Controllers/v1/DemoController.cs [Route("api/v{version:apiVersion}/[controller]")] [ApiVersion(1.0)] [ApiController] public class DemoController : ControllerBase { [HttpGet("[action]")] public ApiResponse Test() { return ApiResponse.Ok("version=1.0"); } }另一个版本的接口 Controllers/v2/DemoController.cs [Route("api/v{version:apiVersion}/[controller]")] [ApiVersion(2.0)] [ApiController] public class DemoController : ControllerBase { [HttpGet("[action]")] public ApiResponse Test() { return ApiResponse.Ok("version=2.0"); } }可以看到要区分不同版本的接口，只需要添加 [ApiVersion(2.0)] 特性即可。 因为我要使用URL来选择不同版本的接口，所以要把路由配置为 "api/v{version:apiVersion}/[controller]" 如果不把版本号写在URL里，也可以用请求参数传递，比如 /api/demo/test?api-version=1.0 这些可以在 ApiVersionReader 属性配置 配置Swaggerswagger基本已经是接口文档的标准了，但我发现很多文章都没有介绍swagger这块。（还好官方文档没有忘记） 首先创建一个配置类 public class ConfigureSwaggerOptions : IConfigureOptions { readonly IApiVersionDescriptionProvider provider; public ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider) => this.provider = provider; public void Configure(SwaggerGenOptions options) { foreach (var description in provider.ApiVersionDescriptions) { options.SwaggerDoc( description.GroupName, new OpenApiInfo() { Title = $"Example API {description.ApiVersion}", Version = description.ApiVersion.ToString(), }); } } }注册服务 builder.Services.AddTransient();配置中间件 app.UseSwagger(); app.UseSwaggerUI(options => { foreach (var description in app.DescribeApiVersions()) { var url = $"/swagger/{description.GroupName}/swagger.json"; var name = description.GroupName.ToUpperInvariant(); options.SwaggerEndpoint(url, name); } }); 效果 & 测试搞定，访问swagger文档，在右上角接口分组可以看到不同版本
请求 https://localhost:7053/api/v1/Demo/Test 接口返回 { "statusCode": 200, "successful": true, "message": "version=1.0", "data": null, "errorData": null }请求 https://localhost:7053/api/v2/Demo/Test 接口返回 { "statusCode": 200, "successful": true, "message": "version=2.0", "data": null, "errorData": null }不错~ 😃 参考资料 https://github.com/dotnet/aspnet-api-versioning/wiki |
【本文地址】